MacTech 1 to 12/MacTech-vol-1-12.toast/Source/MacTech's Sprocket™/Sprocket-10.14.95/Release Notes

Text File | 1995-01-24 | 15.6 KB | 432 lines | [TEXT/MMCC]

#################################################################################################
#
#    Dave’s Release Notes for Sprocket 1.0d23 (1/24/95)
#    (If you just want to see the change history skip ahead to CHANGE HISTORY)
#

Threads and “The Futures”
=========================

Well, this release marks the first official roll-in of Steve Sisak’s AEThreads and Futures
work. While this stuff is pretty cool, there are a couple of things to worry about:

1) If you are using the ObjectSupportLib (e.g., AEResolve) in your AppleEvent handlers, be aware
that much of the AppleEvent registry assumes only a single application thread. What do I mean
by this?  Well, how’s this: What does “window 1” mean in a multithreaded world where your
application might be creating and destroying windows independently of the user interface?

2) Greg Anderson, “a Finder kinda guy” at Apple was busy hacking the scriptable finder the
other day and without knowing it, completely implemented another version of the Futures
package. Sometime in the next century, a DEVELOP magazine article will be coming out outlining
what he did, so be aware that we may attempt to merge his code with Steve’s work-- they
both started from the original code from DEVELOP, so it shouldn’t be too tough.

3) We’l probably be making some significant changes to the AppleEvent and Threading code to
deal with ARM C++-like exception handling.  By the time we get to this, just about every
C++ compiler for the Mac will support real exception handling anyway (THINK C 8.0 seems to
do this, from what I’ve heard; Apple plans to support real exceptions in MrC; and Greg Galanos
already has it on his schedule somewhere).  The work here is that we want to support threadded
AppleEvent handling, some cool object model stuff (from Eric Berdahl, Taligent cult member),
and make it all work with exceptions.


CodeWarrior, Symantec, and Semantics
====================================

Sprocket now requires the use of the Universal Headers 2.0a3. These headers can be
found in CW5 and future versions of the Symantec C++ enironments.

If you are using THINK C, you can either hack the source, or grab the headers [HMMM URL???].

While we’ve made an attempt at making Sprocket work better in THINK C 7.0, we will
try to make things better in the future for every environment (including MPW).

This will become more important as we start trying to take advantage of features like
C++ exception handling, while still trying to be multi-threadable.


Better (or Just Plain Different) Menus
======================================

The biggest change in Sprocket has been a major rearchitecting of menu command handling.
We now have a TMenuBar object which keeps track of “<menu,item> -> <command>” mappings
in a VERY similar manner to what is used in OpenDoc™.

Here’s a quick look at the methods of TMenuBar that are interesting to you:

class TMenuBar
    {
    OSErr                    GetNewMenuBar(short whichMBAR);
    MenuRef                    GetMenuFromCMNU(short whichMenu);

    . . .

    MenuCommandID            GetCommand(MenuID menu, MenuItemID item);
    void                    GetMenuAndItem(MenuCommandID commandNum, MenuID * returnedMenu, MenuItemID * returnedItem);

    OSErr                    RegisterCommand(MenuCommandID commandNum, MenuID menu, MenuItemID item);
    OSErr                    UnregisterCommand(MenuCommandID commandNum);

    void                    EnableCommand(MenuCommandID commandNum, Boolean enable);
    void                    EnableAndCheckCommand(MenuCommandID commandNum, Boolean enable, Boolean check);

    void                    GetItemString(MenuCommandID commandNum,StringPtr itemString);
    void                    SetItemString(MenuCommandID commandNum,StringPtr itemString);

    . . .
    };

The basic idea is that each menu item can have a MenuCommandID (a.k.a. unsigned long) attached
to it. In this way, you can simply assign a numeric constant (e.g., 1000) to a menu item, and
then NEVER EVER CARE where that item actualy lives in your menubar!

In order to an attach a MenuCommandID to a particular menu and item, simple call the method
RegisterCommand:

    gMenuBar->RegisterCommand(cNewWidget,mFileMenu,iNewWidget);


“But that’s not Macintosh”
--------------------------

If you don’t like having to register commands programmatically, you can do what normal folks
do: use resources. Unlike OpenDoc™, we support menu resources which can automatically register
commands without the need for calling RegisterCommand.

Strangely enough, a new resource type for menus with “longint” commands (CMNUs), was created
for MacApp. In the spirit of never doing work you don’t need to do, we happily choose this
resource type for Sprocket’s menu template resources-- ResEdit and Resourceror already know
how to edit CMNUs. [Watch out, ResEdit 2.1.3 will not change the menuID field when renumbering
a CMNU resource as it does with MENU resources].

Unlike MacApp, we don’t do much evil menu manager hacking and lowmem slamming, we use the
CMNU resource as a template, and construct the corresponding menu via normal menu manager
routines. In order to do this, you can either use the methods GetNewMenuBar and/or
GetMenuFromCMNU.


-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
An OpenDoc Tangent:

By the way, if you ARE building an OpenDoc part, you might want to check out two of the
methods in TMenuBar:

    OSErr        GetNewMenuBar(short resourceID);

    Our version of the toolbox routine GetNewMBar which supports CMNU resources. Also
    unlike GetNewMBar, our routine goes ahead an operates on the current menubar. You
    will have to make some changes to make this function OpenDoc-savvy (like dealing
    with ODPlatformMenus instead of MenuRefs, etc.)

    MenuRef        GetMenuFromCMNU(short resourceID);

    This routines takes a CMNU resource ID, and returns a MenuRef (a.k.a. MenuHandle)
    based on the content of the resource. If no CMNU is found, the result is NULL.

With some hacking these routines should be useful for making your OpenDoc part less
“hardcoded” and more resource data-driven. If you don’t want to mess with SOM, I’d
suggest just making these utility functions in your part.
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

Now, back to our program
------------------------

Like the OpenDoc stuff, you can enable/disable/check/change a menu item just by specifying
the command number, instead of a menu and item. This is handy for dealing with controlling
dynamic commands:

    void TMyWindow::Activate(Boolean activating)
        {
         . . .
        if (activating)
            gMenuBar->EnableCommand(cClose,this->CanClose());
         . . .
        }

For now, we’re prepending command constants with a lowercase “c”. This is the MacApp
convention ("c" is for command, as in cClose). This has an unfortunate overlap with
the AppleEvent Registry’s naming scheme ("c" is for class, as in cDocument or cWindow).

Eventually, we’ll probably implement a TCommand class to better support Undo, Redo,
and recordabiity. Since many small application don’t require this, we’ve decided to push
this off to another deadline.


What does this all mean for you?
--------------------------------

The big change for applications built in Sprocket is that HandleMenu has now been rolled
into the Sprocket-baseline.

If you could care less about all this, you can rename your old HandleMenu routine
to be called HandleMenuSelection, and get rid of the first parameter (a TWindow *):

void
HandleMenuSelection(MenuID theMenu, MenuItemID theItem)
    {
    . . .
    }

Notice that you don’t have to deal with desk accessories any more, or all that
“if (!SystemEdit)” crud for the Edit menu anymore.


If you want to use command-based menus, you need to add a routine which gets called
when a menu item with a command is selected:

void HandleMenuCommand(MenuCommandID command)
    {
    switch (command)
        {
        . . .
        case    cAbout:
            MyCoolAboutBox();
            break;

        case    cMyCoolCommand:
            DoMyCoolCommand();
            break;
        . . .
        }
    }

[NOTE:    To make your life a bit easier, Sprocket will automatically invoke QuitApplication()
when a menu is selected with a command number == cQuit.]


Unlike earlier versions of Sprocket, there is no need to handle every command in these
functions.  Part of this is due to Sprocket getting a bit smarter when dealing with
windows and menu handling. Three new methods have been added to TWindow:

    class TWindow
        {
        . . .
        virtual    void        AdjustMenusBeforeMenuSelection(void);
        virtual void        DoMenuSelection(short menu, short item);
        virtual Boolean        DoMenuCommand(MenuCommandID menuCommand);
        . . .
        };

AdjustMenusBeforeMenuSelection, is a hook method has also been provided to allow your program
to enable and disable menu items just before a MenuSelect or MenuKey call is made. This is
useful for checking the current font in the Fonts menu, etc.

Speaking of the Font menu, the DoMenuSelection hooks is provided for handling menu items
without registered commands.

DoMenuCommand is called to pass menu commands directly to the frontmost non-floating window via
a DoMenuCommand method. Another nifty change is to make TWindow deal with closing a window
from the menubar:

Boolean
TWindow::DoMenuCommand(MenuCommandID command)
    {
    . . .
    if (command == cClose)
        {
        if (this->Close() && this->DeleteAfterClose())
            delete this;
        return true;
        }
    . . .
    }

In order to get this behavior you should call through TWindow::Close() from within your own
derived classes.

One thing to note is that since menu commands are routed through non-floating (e.g., document)
windows only, you must handle menu commands for windoids inside your application’s
HandleMenuCommand function.


TDocument
=========

Work on a real TDocument class has begun, and as a result StandardCloseDocument is in
limbo. If you need to use this in the short term, I’d suggest just using the old code.

A couple of us will be doing some brainstorming about this one.  We don’t want people
to be forced into making their applications “document-based”. This is one of the big
limitations of MacApp, and even OpenDoc-- being document-centric tends to add extra
classes and support routines that aren’t needed for utility functions, cool hacks, or
video games.


Bugs? What bugs?
================

We’ve also managed to fix a number of bugs in Sprocket:

    Dave Mark            :    Dealt with early bugs and helped make things easier
    David denBoer        :    Window activation bugs in TWindow::Select
    Leonard Rosenthal    :    Better TSM support
    Randy Thelen        :    Thread performance when quitting & SplashWindow bugs
    Gary Powell            :    TDialogWindow, DialogUtils, C++ disciplines

Some of the GX initialization has been rearranged as suggested by Jon Summers who used
Sprocket to build a PDD (portable digital document) viewer.

A double-dispose problem with the SplashWindow was fixed, and we even decided to support
“empty” splash windows.


What to expect in the future:
=============================

Real documents and GX-savvy printing
Thread-safe exception handling (the next thing requires it)
AppleEvent Object Support for Scripting
A Plug-in architecture (wouldn’t THAT be a cool article for someone to write?)
Embedding OpenDoc and/or OLE things in Sprocket windows


#########################
CHANGE HISTORY for 1.0d23
#########################

The changes in detail (more or less):

    AEThreads.c,1
    AEThreads.h,1
    Futures.c,1
    Futures.h,1
        Added Steve Sisak’s changes to Sprocket to support installing threaded
        AppleEvent handlers and Futures.

    DialogWindow.h,4
    DialogWindow.cp,8
        Adapt to new Menu handling methodology. Also protected the constructor,
        as this is really an abstract class.

        Also fixed bug where we weren’t disposing of TDialogWindows using DisposeDialog.

    MenuBar.h,3
    MenuBar.cp,3
        Added support for CMNU resources, which allows for menu commands to automatically
        be registered without code modification. (cool, eh?) We don’t yet support 'mctb'
        resources for these types.

    Sprocket.h,12
        Added cPreferences command constant.

    DialogUtils.cp,8
        Gary Powell is a bug finding god. Fix an unitialized variable problem in ErrorAlert.

    SplashWindow.cp,8
        Fix a double-dispose bug: there is no need to get rid of a window’s picture.
        DisposeWindow will already KillPicture it.

    SprocketMain.cp,17
        Use our own special version of GetNewMenuBar which should automatically register menu
        commands found in CMNU resources.

    Window.h,8
    Window.cp,14
        Fix the “calling DisposeWindow on DialogPtr” problem reported by Gary Powell @ Adobe
        by adding a cheezy flag that NTWindow initializes, but TDialogWindow slams.
        In TWindow::Close, we check this flag and call DisposeDialog instead of DisposeWindow,
        surely preventing memory leaks for complex dialogs.

    CreditsBox.rsrc,3
        Added Gary Powell & Marshall Clow

    Sprocket.rsrc,5
        bumped 'vers' (2) to d22.

Stuff that was checked in, but isn’t ready for prime time:

    Document.cp,1
    Document.h,1
    Exceptions.cp,1
    Exceptions.h,1
    UAppleObject.cp,1
    UAppleObject.h,1



# ————————————————————————————————————————————————————————————————————————
#    Dave’s Quick and Dirty Release Notes for Sprocket95™ 1/3/95

#        Dynamic arrays
#
#        Added a dynamic array base class for efficient collections
#        of object references. Also added a sorted dynamic array
#        class which can be used to keep a sorted list.

:Sprocket:Interfaces:DynamicArray.h,1
:Sprocket:Lib:DynamicArray.cp,1
:Sprocket:Interfaces:SortedDynamicArray.h,1
:Sprocket:Lib:SortedDynamicArray.cp,1


#        Menu command handling ala OpenDoc™
#        (NOTE: This will be accompanied by an upcoming article)
#
#        A basic class for maintaing the state of the menu bar is
#        another work in progress for an upcoming article. TMenuBar
#        maintains <menu,item> <-> <command> mappings for items
#        in the menu bar. The methods for TMenuBar deliberately
#        resemble those of OpenDoc’s ODMenuBar.
#
#        Unlike OpenDoc, there is only a single, global menubar
#        supported. This MAY change when we decide to support plug-ins
#        and/or embedding of OpenDoc parts.
#
#        Support for building a TMenuBar from an MBAR and (MENU or CMNU)
#        resources has yet to be written, so commands must be manually
#        registered via the RegisterCommand method.

:Sprocket:Interfaces:MenuBar.h,1
:Sprocket:Lib:MenuBar.cp,1


#        Rudimentary document support
#
#        NOTE: This will be accompanied by an upcoming article
#
#        NOTE: This stuff is potentially completely *bogus* and is
#                subject to massive changes in the future.
#
#        In order to better support things like saving and printing
#        in the future, I’m working on a TDocument class. Things like
#        a standard close options dialog, a GX-savvy print loop, etc.
#        will eventually go here. There is also a TDocWindow class
#        for linking a window to a given TDocument.

:Sprocket:Interfaces:Document.h,1
:Sprocket:Lib:Document.cp,1
:Sprocket:Interfaces:DocWindow.h,1
:Sprocket:Lib:DocWindow.cp,1


#    General maintenance

#        Some changes were made in order to adapt to the new menu
#        command scheme:
#
#        TWindow’s DoMenuCommand and AdjustMenusBeforeMenuSelection methods
#        should now work properly, providing simpler menu handling.
#
#        Applications can provide a HandleMenuCommand procedure to handle
#        non-window specific commands. This procedure doesn’t need to do
#        anything.
#
#        Applications must also register a quit command so they will be
#        properly terminated. (NOTE: There is no need to handle Quit within
#        the HandleMenuCommand procedure)

#        Fixed a bug in TSplashWindow which created a stupid minature window
#        even if we didn’t have a splash screen PICT.

#        We also added some cool drag manager utilities and TWindow methods
#        from Nitin Ganatra author of Malph, a way-cool utility.

:Sprocket:Interfaces:Window.h,5
:Sprocket:Interfaces:Sprocket.h,9
:Sprocket:Lib:DialogUtils.cp,7
:Sprocket:Lib:DragUtils.cp,3
:Sprocket:Lib:SplashWindow.cp,7
:Sprocket:Lib:SprocketMain.cp,15
:Sprocket:Lib:Window.h,6
:Sprocket:Lib:Window.cp,12